Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Sequences

DecompressSequenceBegin

The Movie Toolbox handles the details of decompressing image sequences in QuickTime movies. If you need to decompress other sequences, your application calls this function to signal the beginning of the process of decompressing a sequence of frames. You must call this function before calling the DecompressSequenceFrame function (described in the next section).

pascal OSErr DecompressSequenceBegin (ImageSequence *seqID, 
                              ImageDescriptionHandle desc,
                              CGrafPtr port, GDHandle gdh, 
                              const Rect *srcRect, 
                              MatrixRecordPtr matrix, short mode,
                              RgnHandle mask, CodecFlags flags, 
                              CodecQ accuracy,
                              DecompressorComponent codec);

seqID

Contains a pointer to a field to receive the unique identifier for this sequence returned by the CompressSequenceBegin function (described on page 3-100). You must supply this identifier to all subsequent Image Compression Manager functions that relate to this sequence.

desc

Contains a handle to the image description structure that describes the compressed image.

port

Points to the graphics port for the destination image. If this parameter specifies a graphics world or points to the screen, set the gdh parameter to nil. If you set this parameter to nil, the Image Compression Manager uses the current port (in this case, you should also set the gdh parameter to nil).

gdh

Contains a handle to the graphics device record for the destination image. If the port parameter specifies a graphics world or the screen, or if you set the port parameter to nil, set this parameter to nil.

srcRect

Contains a pointer to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height). If you want to decompress the entire source image, set this parameter to nil. If the srcRect parameter is nil, the rectangle is set to the rectangle structure of the image description structure. Your application can change the source rectangle for an active sequence by calling the SetDSequenceSrcRect function (described on page 3-125).

matrix

Points to a matrix structure that specifies how to transform the image during decompression. You can use the matrix structure to translate or scale the image during decompression. If you do not want to apply such effects, set the matrix parameter to nil. For more information about matrix operations, see the chapter "Movie Toolbox" in this book.

Your application can change the matrix for an active sequence by calling the SetDSequenceMatrix function (described on page 3-125).

mode

Specifies the transfer mode for the operation. The Image Compression Manager supports the same transfer modes supported by QuickDraw's CopyBits routine (described in Inside Macintosh: Imaging).

Your application can change the transfer mode for an active sequence by calling the SetDSequenceTransferMode function (described on page 3-124).

mask

Contains a handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you do not want to mask pixels in the destination, set this parameter to nil.

Your application can change the clipping mask for an active sequence by calling the SetDSequenceMask function (described on page 3-126).

flags

Contains flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on page 3-58, for information about CodecFlags fields. The following flags are available for this function:

codecFlagUseScreenBuffer

Controls whether the decompressor allocates an offscreen buffer. The decompressor places the decompressed image into that buffer and then copies the image to the destination pixel map after completing the decompression operation. Using an offscreen buffer reduces the tearing effect that can result from writing directly to the screen during decompression. Set this flag to 1 to cause the decompressor to allocate and use an offscreen buffer. Set this flag to 0 to cause the decompressor to write to the destination pixel map.

Your application can determine the screen buffer for an active sequence by calling the GetDSequenceScreenBuffer function (described on page 3-130).

codecFlagUseImageBuffer

Controls whether the decompressor allocates an offscreen buffer for the current image. The decompressor uses
this buffer to store the compressed data from the current image so that subsequent images that are temporally compressed can be processed correctly. Set this flag to 1 to cause the decompressor to use an image buffer. Set this flag to 0 if your sequence is not temporally compressed and therefore does not require the use of an image buffer.

Your application can determine the image buffer for an active sequence by calling the GetDSequenceImageBuffer function (described on page 3-130).

accuracy

Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See "Compression Quality Constants" beginning on page 3-57 for available values.

Your application can change the accuracy parameter for an active sequence by calling the SetDSequenceAccuracy function (described on page 3-128).

codec

Contains a compressor identifier. Specify a particular decompressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first decompressor of the specified type

bestSpeedCodec

Choose the fastest decompressor of the specified type

bestFidelityCodec

Choose the most accurate decompressor of the specified type

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

If you set the codec parameter to anycodec, the Image Compression Manager chooses the first decompressor it finds of the specified type.

DESCRIPTION

Use the SetDSequenceDataProc function (described on page 3-129) to assign a data-loading function to the sequence. Use the SetDSequenceMatte function (described on page 3-127) to assign a blend matte to the sequence.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor
codecScreenBufErr	-8964	Could not allocate the screen buffer
codecImageBufErr	-8965	Could not allocate the image buffer
codecConditionErr	-8972	Component cannot perform requested operation